﻿@page "/docs/components/field"

<Seo Canonical="/docs/components/field" Title="Blazorise Field Component - Form Layout & Input Grouping" Description="Learn how to use the Blazorise Field component to structure form layouts, align labels, add help text, and group input controls using Bootstrap-inspired patterns." />

<DocsPageTitle Path="Components/Field">
    Blazorise Field component
</DocsPageTitle>

<DocsPageLead>
    A flexible layout container used to organize and align form input components for better usability, accessibility, and structure.
</DocsPageLead>

<DocsPageParagraph>
    The <Code Tag>Field</Code> component acts as a lightweight form layout wrapper that groups a label, input control, help text, and validation message into a single, consistent container.
    It works with common Blazorise form controls such as <Code>TextEdit</Code>, <Code>Select</Code>, <Code>DateEdit</Code>, <Code>Check</Code>, <Code>MemoEdit</Code>, and optionally <Code>Button</Code>.
    Its structure is intentionally minimal, making it easy to build clear, predictable, and accessible form layouts.
</DocsPageParagraph>

<UnorderedList>
    <UnorderedListItem>
        <Paragraph>
            <Code Tag>Field</Code> the main container.
        </Paragraph>
        <UnorderedList>
            <UnorderedListItem>
                <Paragraph>
                    <Code Tag>FieldLabel</Code> used for the label of the field.
                </Paragraph>
            </UnorderedListItem>
            <UnorderedListItem>
                <Paragraph>
                    <Code Tag>FieldBody</Code> the container for the input control.
                </Paragraph>
            </UnorderedListItem>
            <UnorderedListItem>
                <Paragraph>
                    <Code Tag>FieldHelp</Code> used for the help text.
                </Paragraph>
            </UnorderedListItem>
        </UnorderedList>
    </UnorderedListItem>
    <UnorderedListItem>
        <Paragraph>
            <Code Tag>Fields</Code> container used to group several <Code>Field</Code> components
        </Paragraph>
    </UnorderedListItem>
</UnorderedList>

<DocsPageParagraph>
    It is recommended to always place input components inside of a <Code>Field</Code>. That way you will keep consistent spacing,
    alignment, and arrangement between input controls across your forms.
</DocsPageParagraph>

<DocsPageSubtitle>
    Examples
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="Basic">
        To properly structure your form, wrap each input control inside a <Code>Field</Code> component to keep labels, help text, and validation messages aligned consistently.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <BasicFieldExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="BasicFieldExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Label">
        Every input should have a clear, descriptive label that explains its purpose in plain language. Use <Code Tag>FieldLabel</Code> to associate the label with the control, and <Code>FieldHelp</Code> when additional guidance is needed.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <FieldWithLabelExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="FieldWithLabelExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Helper">
        Helper text provides inline guidance or additional context for a field. It can contain plain text, HTML, or other components and should clarify how to fill out the input without repeating the label.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <FieldWithHelpExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="FieldWithHelpExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Read-Only">
        Set a field as read-only when the value should be visible but not editable. Read-only inputs remain in the tab order, can receive focus, and their contents can still be selected and copied by the user.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <FieldWithReadOnlyExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="FieldWithReadOnlyExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Disabled">
        <Paragraph>
            Disable a field to mark it as unavailable when the user should not interact with it. Disabled inputs cannot receive focus or be edited.
        </Paragraph>
        <Paragraph>
            Disabling a field is often preferable to hiding it because it preserves the layout and lets users see that the option exists, even if it is currently unavailable.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <FieldWithDisabledExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="FieldWithDisabledExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Horizontal field">
        <Paragraph>
            Use a horizontal field when you want the label and input to appear side-by-side in a single row. Combine <Code Tag>FieldLabel</Code> and <Code Tag>FieldBody</Code> with <Code>ColumnSize</Code> to control how much space each part occupies.
        </Paragraph>
        <Paragraph>
            When using a <Code Tag>Check</Code> component inside a horizontal field, align it with the label by applying <Code>Margin="Margin.IsAuto"</Code> or similar spacing utilities.
        </Paragraph>
        <Paragraph>
            <Strong>Note</Strong>: Horizontal fields are inspired by Bootstrap horizontal form layout, and only one horizontal field should be placed per row to keep the grid aligned.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <HorizontalFieldExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="HorizontalFieldExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Visibility">
        Use the <Code>Visibility</Code> attribute to hide a field while still preserving its space in the layout, so surrounding content does not shift unexpectedly.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <FieldHiddenExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="FieldHiddenExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Fields">
        The <Code Tag>Fields</Code> component is used to group multiple <Code Tag>Field</Code> components. Use it to build rows or columns of related fields that share layout settings and spacing.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <BasicFieldsExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="BasicFieldsExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Validation Indicator">
        In Blazorise, you can use the <Code>RequiredIndicator</Code> feature to automatically display an indicator (such as an asterisk) next to labels of required fields. This helps users quickly understand which inputs are mandatory and improves overall form usability.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <RequiredIndicatorExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="RequiredIndicatorExample" />
</DocsPageSection>

<DocsPageSubtitle>
    Best Practices
</DocsPageSubtitle>

<Heading Size="HeadingSize.Is3">
    Do
</Heading>

<DocsPageParagraph>
    <UnorderedList>
        <UnorderedListItem>
            <Paragraph>Use <Code Tag>Field</Code> to provide a consistent label, layout, and validation message for each form control.</Paragraph>
        </UnorderedListItem>
        <UnorderedListItem>
            <Paragraph>Use <Code Tag>Field</Code> to label controls that do not have built-in labels, such as <Code Tag>ProgressBar</Code> or custom components.</Paragraph>
        </UnorderedListItem>
        <UnorderedListItem>
            <Paragraph>Use <Code Tag>Fields</Code> to group related <Code Tag>Field</Code> components when building multi-column or sectioned form layouts.</Paragraph>
        </UnorderedListItem>
    </UnorderedList>
</DocsPageParagraph>

<Heading Size="HeadingSize.Is3">
    Don't
</Heading>

<DocsPageParagraph>
    <UnorderedList>
        <UnorderedListItem>
            <Paragraph>Avoid combining a long validation message and extensive helper text in the same field, as this can overwhelm users.</Paragraph>
        </UnorderedListItem>
        <UnorderedListItem>
            <Paragraph>Don't add multiple interactive controls as children of a single <Code Tag>Field</Code>. The label should clearly describe one primary control for better accessibility.</Paragraph>
        </UnorderedListItem>
    </UnorderedList>
</DocsPageParagraph>

<DocsPageParagraph>
    Related components include <Code Tag>FieldLabel</Code>, <Code Tag>FieldBody</Code>, <Code Tag>FieldHelp</Code>, <Code Tag>TextEdit</Code>, <Code Tag>Select</Code>, and <Code Tag>Check</Code>. Together they help you build accessible and visually consistent forms.
</DocsPageParagraph>

<DocsPageParagraph>
    In summary, the <Code Tag>Field</Code> component simplifies form layout in Blazorise by aligning labels, inputs, help text, and validation messages, while the <Code Tag>Fields</Code> container lets you organize multiple fields into structured sections.
</DocsPageParagraph>

<ComponentApiDocs ComponentTypes="[typeof(Field),typeof(FieldLabel),typeof(Fields)]" />